home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kpluginselector.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-05-22  |  8.5 KB  |  219 lines
  1. /*  This file is part of the KDE project
  2.     Copyright (C) 2002-2003 Matthias Kretz <kretz@kde.org>
  3.  
  4.     This library is free software; you can redistribute it and/or
  5.     modify it under the terms of the GNU Library General Public
  6.     License version 2 as published by the Free Software Foundation.
  7.  
  8.     This library is distributed in the hope that it will be useful,
  9.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  10.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11.     Library General Public License for more details.
  12.  
  13.     You should have received a copy of the GNU Library General Public License
  14.     along with this library; see the file COPYING.LIB.  If not, write to
  15.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16.     Boston, MA 02110-1301, USA.
  17.  
  18. */
  19.  
  20. #ifndef KPLUGINSELECTOR_H
  21. #define KPLUGINSELECTOR_H
  22.  
  23. #include <qwidget.h>
  24. #include <qstring.h>
  25.  
  26. #include <kdelibs_export.h>
  27.  
  28. class KInstance;
  29. class KPluginInfo;
  30. class QWidgetStack;
  31. class KConfig;
  32. class KConfigGroup;
  33.  
  34. /**
  35.  * @ingroup main
  36.  * @ingroup plugin
  37.  * @short A widget to select what plugins to load and configure the plugins.
  38.  *
  39.  * It shows the list of available plugins on top (if there's more than one
  40.  * category this is a TabWidget) and the configuration of the selected plugin
  41.  * below that.
  42.  *
  43.  * Since the user needs a way to know what a specific plugin does every plugin
  44.  * sould install a desktop file containing a name, comment and category field.
  45.  * The category is usefull for applications that can use different kinds of
  46.  * plugins like a playlist, skin or visualization.
  47.  *
  48.  * The location of these desktop files is the
  49.  * share/apps/<instancename>/<plugindir> directory. But if you need
  50.  * you may use a different directory.
  51.  *
  52.  * Often a program has more than one kind of plugin. In that case you want to
  53.  * make a visible distinction between those plugins. All you have to do is to
  54.  * create a KPluginSelectionWidget for every category and then add them all
  55.  * to the KPluginSelector.
  56.  *
  57.  * @author Matthias Kretz <kretz@kde.org>
  58.  * @since 3.2
  59.  */
  60. class KUTILS_EXPORT KPluginSelector : public QWidget
  61. {
  62.     friend class KPluginSelectionWidget;
  63.  
  64.     Q_OBJECT
  65.     public:
  66.         /**
  67.          * Create a new KPluginSelector.
  68.          */
  69.         KPluginSelector( QWidget * parent, const char * name = 0 );
  70.         ~KPluginSelector();
  71.  
  72.         /**
  73.          * Add a list of KParts plugins
  74.          *
  75.          * If you want to support non-KParts plugins use the following
  76.          * function.
  77.          *
  78.          * The information about the plugins will be loaded from the
  79.          * share/apps/<instancename>/kpartplugins directory.
  80.          *
  81.          * @param instanceName The name of the KInstance of the plugin's parent.
  82.          * @param catname      The translated name of the category. This is the
  83.          *                     name that is shown in the TabWidget if there is
  84.          *                     more than one category.
  85.          * @param category     When you have different categories of KParts
  86.          *                     plugins you distinguish between the plugins using
  87.          *                     the Category key in the .desktop file. Use this
  88.          *                     parameter to select only those KParts plugins
  89.          *                     with the Category key == @p category. If @p
  90.          *                     category is not set the Category key is ignored
  91.          *                     and all plugins are shown.
  92.          * @param config       The KConfig object that holds the state of the
  93.          *                     plugins being enabled or not. By default it should
  94.          *                     be instance->config(). It is recommended to
  95.          *                     always pass a KConfig object if you use
  96.          *                     KSettings::PluginPage since you never know from where the
  97.          *                     page will be called (think global config app).
  98.          *                     For example KViewCanvas passes KSimpleConfig(
  99.          *                     "kviewcanvas" ).
  100.          */
  101.         void addPlugins( const QString & instanceName,
  102.                 const QString & catname = QString::null,
  103.                 const QString & category = QString::null,
  104.                 KConfig * config = 0 );
  105.  
  106.         /**
  107.          * Add a list of KParts plugins. Convenience method for the one above.
  108.          * If not set explicitely, @p config is set to instance->config().
  109.          */
  110.         void addPlugins( const KInstance * instance,
  111.                 const QString & catname = QString::null,
  112.                 const QString & category = QString::null,
  113.                 KConfig * config = 0 );
  114.  
  115.         /**
  116.          * Add a list of non-KParts plugins
  117.          *
  118.          * @param plugininfos  A list of KPluginInfo objects containing the
  119.          *                     necessary information for the plugins you want to
  120.          *                     add to the list.
  121.          * @param catname      The translated name of the category. This is the
  122.          *                     name that is shown in the TabWidget if there is
  123.          *                     more than one category.
  124.          * @param category     When you have different categories of KParts
  125.          *                     plugins you distinguish between the plugins using
  126.          *                     the Category key in the .desktop file. Use this
  127.          *                     parameter to select only those KParts plugins
  128.          *                     with the Category key == @p category. If @p
  129.          *                     category is not set the Category key is ignored
  130.          *                     and all plugins are shown.
  131.          * @param config       The KConfig object that holds the state of the
  132.          *                     plugins being enabled or not. By default it will
  133.          *                     use KGlobal::config(). It is recommended to
  134.          *                     always pass a KConfig object if you use
  135.          *                     KSettings::PluginPage since you never know from where the
  136.          *                     page will be called (think global config app).
  137.          *                     For example KViewCanvas passes KSimpleConfig(
  138.          *                     "kviewcanvas" ).
  139.          */
  140.         void addPlugins( const QValueList<KPluginInfo*> & plugininfos,
  141.                 const QString & catname = QString::null,
  142.                 const QString & category = QString::null,
  143.                 KConfig * config = 0 );
  144.  
  145.         /**
  146.          * Set whether the area for showing the KCMs of the plugins should be
  147.          * hidden if the plugin doesn't have a KCM or whether the layout should
  148.          * rather stay static and only an message should be shown.
  149.          *
  150.          * By default the config page is not hidden.
  151.          */
  152.         void setShowEmptyConfigPage( bool );
  153.  
  154.         /**
  155.          * Load the state of the plugins (selected or not) from the KPluginInfo
  156.          * objects. For KParts plugins everything should work automatically. For
  157.          * your own type of plugins you might need to reimplement the
  158.          * KPluginInfo::isPluginEnabled() method. If that doesn't fit your needs
  159.          * you can also reimplement this method.
  160.          */
  161.         void load();
  162.  
  163.         /**
  164.          * Save the configuration
  165.          */
  166.         void save();
  167.  
  168.         /**
  169.          * Change to applications defaults
  170.          */
  171.         void defaults();
  172.  
  173.     signals:
  174.         /**
  175.          * Tells you whether the configuration is changed or not.
  176.          */
  177.         void changed( bool );
  178.  
  179.         /**
  180.          * Emitted after the config of an embedded KCM has been saved. The
  181.          * argument is the name of the parent component that needs to reload
  182.          * its config
  183.          */
  184.         void configCommitted( const QCString & instanceName );
  185.  
  186.     private:
  187.         /**
  188.          * return the KCM widgetstack
  189.          *
  190.          * @internal
  191.          */
  192.         QWidgetStack * widgetStack();
  193.  
  194.         /**
  195.          * Show an info page in the widgetstack.
  196.          *
  197.          * @internal
  198.          */
  199.         void configPage( int id );
  200.  
  201.         /**
  202.          * @internal
  203.          */
  204.         void checkNeedForTabWidget();
  205.  
  206.         /**
  207.          * @internal
  208.          */
  209.     void addPluginsInternal( const QValueList<KPluginInfo*> plugininfos,
  210.                                  const QString & catname, const QString & category,
  211.                                  KConfigGroup* cfgGroup );
  212.  
  213.     class KPluginSelectorPrivate;
  214.         KPluginSelectorPrivate * d;
  215. };
  216.  
  217. // vim: sw=4 sts=4 et tw=80
  218. #endif // KPLUGINSELECTOR_H
  219.